Einheit 5 — Nachschlagen statt raten

Was du nach dieser Einheit weißt: Du findest zu jeder Aufgabe den passenden Node-Typ, kennst dessen echte Optionen und weißt, welche Zugangsdaten und API-Spezifikationen dir zur Verfügung stehen.

Der häufigste Grund für einen Workflow, der nicht tut, was er soll: Eine Option heißt anders als angenommen. TowelScript prüft Optionsnamen nicht — ein Tippfehler in post_url fällt beim Compile nicht auf, sondern erst im Log, wenn der Agent nichts sendet.

Deshalb: nachschlagen. Es dauert zehn Sekunden.

Node-Typen finden — `towelscript_catalog`

Der Katalog liefert alle 75 Node-Typen mit dem dahinterliegenden Agent und den Aliasnamen:

{
  "name": "http",
  "agent": "Agents::PostAgent",
  "category": "output",
  "aliases": ["http.post"]
}

Du kannst nach Kategorie filtern: input (15 Typen), processing (50), output (10).

Die wichtigsten Typen nach Aufgabe

Aufgabe	Node-Typ	Agent
Formular bereitstellen	`form`	WebFormAgent
E-Mails empfangen	`imap`	IncomingMailAgent
Von außen angestoßen werden	`webhook`	WebhookAgent
Ordner überwachen	`smb.watch`, `nextcloud.watch`	SMB-/Nextcloud-Monitor
Testnachricht einspeisen	`manual`	ManualMessageAgent
Datei auslesen	`pdf.read` (Alias `file.read`)	ReadFileAgent
Excel lesen / schreiben	`excel.read` / `excel.create`	Excel-Agents
KI-Auswertung	`ai`	GenAiAgent
JSON parsen / aufteilen / filtern	`json`, `json.split`, `json.filter`	JSON-Agents
Bedingung prüfen	`filter`	TriggerAgent
Verzweigen	`switch`	SwitchAgent
Daten zwischenspeichern (SQL)	`storage`	InternalStorageAgent
Freigabe einholen	`task` (Alias `approve`)	HumanTaskAgent
Eigene Logik in JavaScript	`map` (Alias `javascript`)	JavaScriptAgent
REST-Request senden	`http.post`	PostAgent
E-Mail senden	`notify` (Alias `email.send`)	EmailAgent

Aliasnamen nutzen

http allein kompiliert nur dann zum Post Agent, wenn post_url gesetzt ist — andernfalls rät der Compiler auf Agents::WebsiteAgent. Schreib deshalb immer den eindeutigen Alias http.post.

Optionen nachschlagen — `agent_docs`

agent_docs ist das wichtigste Werkzeug dieser Einheit. Es beantwortet für jeden Agent:

Welche Optionen gibt es, welchen Typ haben sie, was ist der Standardwert?
Welche Payload erwartet er?
Welche Payload gibt er aus?
Die vollständige deutschsprachige Dokumentation aus der Oberfläche

Du kannst danach auf drei Wegen fragen:

Parameter	Beispiel	Wann
`towelscript_type`	`form`	Wenn du aus TowelScript heraus arbeitest — bevorzugt
`agent_type`	`Agents::WebFormAgent`	Wenn du den Rails-Klassennamen kennst
`agent_id`	`1900`	Wenn du einen konkreten bestehenden Agent untersuchst

Ein Ausschnitt aus der Antwort für form:

{
  "default_options": {
    "secret": "formsecret",
    "form_fields": "[{\"name\":\"message\",\"label\":\"Nachricht\",\"type\":\"text\"}]",
    "response_text": "Form received",
    "custom_css": ""
  }
}

Und in der Beschreibung stehen Dinge, die man sonst nie findet — etwa dass der Web Form Agent Felder abhängig voneinander zu Pflichtfeldern machen kann:

[
  { "name": "decision", "label": "Entscheidung", "type": "radio",
    "options": ["Genehmigen", "Ablehnen"], "required": true },
  { "name": "reason", "label": "Begruendung", "type": "text",
    "required_if": { "field": "decision", "value": "Ablehnen" } }
]

Die Arbeitsweise

Bevor du einen Node-Typ zum ersten Mal einsetzt, lass dir seine Dokumentation zeigen:

„Zeig mir die Dokumentation für den storage-Node."

Das kostet einen Werkzeugaufruf und spart dir die halbe Stunde, in der du sonst rätst, warum nichts ankommt.

📸 Screenshot: [Platzhalter — Claude Code zeigt die agent_docs-Ausgabe für einen Node-Typ]

Zugangsdaten — `credential_list`

credential_list liefert die Namen aller hinterlegten Zugangsdaten — nie die Werte:

{
  "credentials": [
    { "name": "IMAP_invoice" },
    { "name": "Pipedrive_token" },
    { "name": "SMTP_jonas" },
    { "name": "Timebutler_API_Token" }
  ]
}

Damit kennst du die exakten Namen für @secret(…). Anlegen oder ändern kannst du Zugangsdaten über MCP nicht — das geht ausschließlich in der Oberfläche. Das ist Absicht.

API-Spezifikationen — `api_spec_*`

Wenn du in 42°flow eine OpenAPI-/Swagger-Datei hinterlegt hast, kannst du dir daraus eine fertige Post-Agent-Konfiguration bauen lassen:

api_spec_list — welche Spezifikationen gibt es?
api_spec_show — welche Endpunkte enthält sie? (jeder bekommt einen endpoint_index)
api_spec_post_agent_config — baut aus Spezifikation + Endpunkt-Index die Optionen für den Post Agent

Das ersetzt die Handarbeit aus Kurs 3, Einheit „Von curl zum Post Agent" — allerdings nur für Endpunkte, deren Spezifikation vorliegt.

Hinweis

Sind keine Spezifikationen hinterlegt, liefert api_spec_list eine leere Liste. Dann bleibt der Weg aus Kurs 3: Request von Hand aus der API-Dokumentation nachbauen.

Bestehende Workflows als Vorlage

Der schnellste Weg zu einer korrekten Konfiguration ist oft ein Workflow, in dem dasselbe schon funktioniert:

„Schau dir an, wie der Workflow 010 | E-Mail-Eingang seinen IMAP-Agent konfiguriert hat, und baue mir denselben Aufbau für das Postfach X."

workflow_show liefert die vollständigen Optionen aller Agents. Was dort produktiv läuft, ist erprobt — das ist mehr wert als jede Dokumentation.

Zusammengefasst

Frage	Werkzeug
Welcher Node-Typ macht das?	`towelscript_catalog`
Welche Optionen kennt er?	`agent_docs` mit `towelscript_type`
Wie heißt die Zugangsdaten-Referenz?	`credential_list`
Gibt es eine API-Spezifikation?	`api_spec_list` → `api_spec_show`
Wie hat das schon mal jemand gelöst?	`workflow_show` auf einen bestehenden Workflow

Weiter: Übung — Deinen ersten Workflow per TowelScript deployen

Node-Typen finden — towelscript_catalog​

Die wichtigsten Typen nach Aufgabe​

Optionen nachschlagen — agent_docs​

Zugangsdaten — credential_list​

API-Spezifikationen — api_spec_*​

Bestehende Workflows als Vorlage​

Zusammengefasst​